Linux Cubed Series 2: Applications

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / oo-browser.info-1 < prev next >

Wrap

GNU Info File | 1995-09-01 | 47.0 KB | 1,111 lines

This is Info file ../info/oo-browser.info, produced by Makeinfo-1.63 from the input file oo-browser.texi. File: oo-browser.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Preface ******* Copyright (C) 1989-1995 Free Software Foundation, Inc. All trademarks referenced herein are trademarks of their respective holders. This edition of the OO-Browser User Manual is for use with any version 2.9.8 or greater of the OO-Browser. The OO-Browser is available for free use, distribution, and modification under the terms of version 2 or later of the GNU Public License (GPL). No representations are made about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. The OO-Browser was designed and written by Bob Weiner. Motorola, Inc. funded and donated this work for free redistribution as part of the InfoDock integrated productivity toolset. Torgeir Veimo and Mark Stern helped write the X OO-Browser core. Don Yacktman helped write the NEXTSTEP OO-Browser core. Jeff Sparkes helped with the Java language support. The OO-Browser and InfoDock can be obtained via anonymous ftp on the Internet from: `/anonymous@cs.uiuc.edu:/pub/xemacs/infodock'. Installation instructions for the OO-Browser can be found in the `BR-README' file in the OO-Browser distribution. This manual documents the user interface and operation of the OO-Browser multi-language browser. It assumes a very basic familiarity in the use of the GNU Emacs editor as documented in `[Stallman 87]'. It also assumes familiarity with object-oriented software concepts. However, many technical terms used in this manual are given precise meaning in the glossary. *Note Glossary::. The OO-Browser is meant to be easy to use, so you can point and click to use it, rather than learning all of the key stroke commands. Chapter 1 of the manual focuses on OO-Browser Environments to provide the reader with a picture of how to organize work for use with the OO-Browser (*note Working with Environments: Environments.). *Note Using the OO-Browser: Usage, if you would rather start with the interactive features of the browser. *Note OO-Browser Features: Features, for a quick overview of the browser's features. Throughout this manual, sequences of key strokes are delimited by braces, {}, command names are delimited by parentheses, (), and variable names are emphasized. We hope that you enjoy using the OO-Browser and that it improves your productivity. * Menu: * Introduction:: Introduction * Environments:: Working with Environments * Usage:: Using the OO-Browser * Options:: OO-Browser Options * Customization:: Personal Customization * Standalone:: Using Standalone OO-Browser Features * Languages:: Language-Specific Notes * Features:: OO-Browser Features * Commands:: OO-Browser Command Descriptions * Glossary:: Glossary * References:: References * Keys:: Key Binding Index * Command Index:: Command and Variable Index * Concepts:: Concept Index -- The Detailed Node Listing -- Working with Environments * Creating Environments:: * Building Environments:: * Loading Environments:: * Saving Environments:: Using the OO-Browser * Invoking:: Invoking the OO-Browser * Top-Level Classes:: Displaying Top-Level Classes * Moving to Entries:: * Saving Listings:: Writing a Listing to a File * Children and Parents:: Browsing Children and Parents * Descendants and Ancestors:: Browsing Descendants and Ancestors * Viewing and Editing:: Viewing and Editing Classes * Browsing Elements:: * Browsing Categories:: * Browsing Protocols:: * Browsing Implementors:: * Exiting a Listing:: * Quitting and Refreshing:: Quitting and Refreshing the OO-Browser * Using the Mouse:: * Getting Help:: * Locating Entries:: * Filtering Entries:: * Ordering Entries:: * Statistics:: Environment and Class Summaries * Class Info:: Language-Specific Class Information * Adding and Deleting Classes:: * Completing Names:: * Graphical Browsing:: Graphical OO-Browser Interfaces OO-Browser Options * External Viewing:: Using An External Viewer or Editor * Keep Viewed Classes:: * Inhibit Version:: Inhibit Version Screen * Invert Ancestors:: Invert Ancestor Trees * Save All:: Save All Lookup Tables * Use Children:: Build Children Lookup Table * Sort Options:: Controlling Class Listing Order Language-Specific Notes * C Specifics:: * C++ Specifics:: * CLOS Specifics:: * Eiffel Specifics:: * Java Specifics:: * Objective-C Specifics:: C++ Specifics * C++ Element Selection:: Source Code Element Selection * C++ Settings:: CLOS Specifics * CLOS Method Handling:: Method Handling * CLOS Settings:: Eiffel Specifics * Eiffel Listings:: * Eiffel Element Selection:: Source Code Element Selection * Eiffel Settings:: Objective-C Specifics * Objective-C Categories:: * Objective-C Protocols:: * Objective-C Element Selection:: Source Code Element Selection * Objective-C Settings:: File: oo-browser.info, Node: Introduction, Next: Environments, Prev: Top, Up: Top Introduction ************ The "OO-Browser" is a multi-windowed, interactive, object-oriented class browser designed for professional use. Its user interface is similar to the well-known Smalltalk browsers `[Goldberg 83]', yet it is much more flexible and easy to use. The OO-Browser is unique in several respects: * It currently supports six object-oriented languages (Eiffel, C++, Objective-C, CLOS (Lisp), Java and Smalltalk), one non-object-oriented language (C), and one documentation language, (GNU Info). * It may be used for both system exploration and for browsing purposes as part of a professional software development tool chest. * It quickly displays and provides views of complicated inheritance trees, making it an important tool for understanding object-oriented systems. * It has a completely direct-manipulation interface with multiple modalities. * It is integrated with a powerful editing environment that can be customized to meet personal work styles. The picture on the following page highlights the major components of the OO-Browser user interface. (If you are reading the online Info version of this manual, see the last paragraph of this node for a link to the aforementioned picture.) The windows across the top of the OO-Browser frame are called "class listing windows"; they display "listing buffers" with a single class name per line. The "viewer window" fills the bottom half of the frame. It is used to display class source and summary information. It is also used to display help on the OO-Browser command set. Pictured here in the viewer window is part of the browser help buffer, summarizing its command key bindings. All key bindings described throughout this manual are effective only within listing buffers, unless otherwise indicated. This means that the keys may not be used within the buffers displayed in the class viewer window. Instead, all normal editing keys are available in most buffers displayed in the viewer window. Mouse click on the following filename to view a picture of the textual OO-Browser: "im/oobr-text.eps". Under InfoDock, use the middle mouse button. Under Emacs with the Hyperbole system loaded, use the shift-middle mouse button or shift-left on a two button mouse. Otherwise, there is no built-in way to view the picture. File: oo-browser.info, Node: Environments, Next: Usage, Prev: Introduction, Up: Top Working with Environments ************************* Whenever the OO-Browser is in use, an Environment is selected. An Environment may be built or simply specified. An "Environment specification" tells the browser what to include in the construction of an Environment. (*Note Creating Environments::, for more information.) An OO-Browser "Environment" includes a set of inter-class relationships together with a few browser settings. The phrase, "the Environment", refers to the current OO-Browser Environment. Many browser commands depend on information in the Environment. The set of classes included in an Environment is specified by two lists of directories, below which all of the Environment's class source files are to be found. (The OO-Browser will automatically search sub-directories below the directories specified.) The first list of directories is called the "Library search list"; it defines the locations of stable, typically reusable classes that have been released for general use. The second list is called the "System search list"; it defines the locations of unreleased classes being developed, often for a particular system. All class names within a single Environment must be unique to ensure proper operation of the browser. The OO-Browser lets one create, update and save Environments. Once an Environment file has been created, it may be loaded at any time. The browser will then use this Environment for all of its operations until another one is loaded. The browser maintains a separate Environment for each programming language on which it is used. Thus, if one switches from Eiffel to C++ browsing and then back to Eiffel browsing, the Eiffel environment will not need to be reloaded; it will appear immediately and the frame will appear as if the Eiffel OO-Browser were invoked for the first time. The recommended default name for Environment files is, `OOBR'. We recommend that you store each Environment in the top-level directory of the first system pathname in the Environment, i.e. the root directory of a system's code. Environment files are automatically created and loaded by the OO-Browser so that you need never become familiar with their format. You are responsible for remembering which Environment files you create and for requesting their use whenever desired. *Note Invoking the OO-Browser: Invoking, for information on how to specify a different Environment file for use. * Menu: * Creating Environments:: * Building Environments:: * Loading Environments:: * Saving Environments:: File: oo-browser.info, Node: Creating Environments, Next: Building Environments, Prev: Environments, Up: Environments Creating Environments ===================== Environment specifications are useful when one wants to describe a number of Environments to the OO-Browser but wants to defer their construction until later. Large environments then can be built overnight. *Note Building Environments::, for more information. Every Environment must be specified before it can be built or used. Thus, specifying an Environment is the first step in creating it. Environment specifications are created with the {`C-c C-c'} `(br-env-create)' command, which prompts for all necessary information. This command may be invoked repeatedly to quickly specify a number of different Environments. Here are the Environment specification components for which you will be prompted: `System search directories' List of directories below which other System directories containing class source code and directories of class source files may be found. `Library search directories' List of directories below which Library files of class source code and directories of class source files may be found. *EIFFEL NOTE: We strongly suggest that if you have previous versions of library class source below any of these directories, that you move them elsewhere, e.g. ISE's Eiffel version "2.1" directory of source. These will cause class naming conflicts that the browser will not resolve to your satisfaction. The basic rule is that every class name within a single Environment should be unique. Use {`M-e'} to help find duplicate classes.* File: oo-browser.info, Node: Building Environments, Next: Loading Environments, Prev: Creating Environments, Up: Environments Building Environments ===================== An Environment specification tells the OO-Browser what to include in the Environment, but the Environment still must be built before use. When a new Environment must be built or when a large number of changes have been made to classes in the Environment, the following commands are useful: `{C-c C-e}' build all Env classes `(br-env-rebuild)' (This prompts for whether or not to use a background process to build the Environment.) `{L}' build Env Library classes only `(br-lib-rebuild)' `{S}' build Env System classes only `(br-sys-rebuild)' When class names or locations have changed or the Environment's inheritance structure is modified, the Environment must be rebuilt. For small Environment changes, one may use the class addition and deletion features of the browser. *Note Adding and Deleting Classes::, for more information. The OO-Browser lets you build large environments in the background so you can go on to other work while waiting on a build. When the build is complete, it will ask you whether you want to browse the built Environment. Alternatively, very large Environments may be built overnight by invoking Emacs in batch mode at a scheduled time. The shell command line to use is of the form (substitute your local OO-Browser installation directory for *<BR-DIR>* below): emacs -batch -l <BR-DIR>/br-start.el *Env-Spec-File* \ ... *Spec File* -f br-env-batch-build > log-file for example: emacs -batch -l br-start.el OOBR -f br-env-batch-build > log-file Typically when using the above command line, one should redirect the standard output stream to a log file for later examination, as is done in the above example. This helps ensure that either the Environment built successfully or a message indicating the cause of failure is provided. Note that the Environment specification file must have been created prior to execution of this command so that the browser knows what to build. File: oo-browser.info, Node: Loading Environments, Next: Saving Environments, Prev: Building Environments, Up: Environments Loading Environments ==================== A new Environment may be loaded for use at any time within the OO-Browser. One may either select the load Environment command from the OO-Browser command summary or simply use the language-specific browser invocation command originally used to start the browser, except this time, precede it by a prefix argument. For example, {`C-u C-c C-e'} which invokes `(eif-browse)', would prompt for and then load a new Eiffel environment, even when one is already browsing an Eiffel environment. File: oo-browser.info, Node: Saving Environments, Prev: Loading Environments, Up: Environments Saving Environments =================== The OO-Browser automatically builds and saves Environments in most cases. Occasionally one may find a need to force the Environment to be saved to a file, as in the case when one wants to save an Environment under a different file name. Use {`C-c C-s'}, the `(br-env-save)' command to force an Environment save to occur. The command will prompt for a file to save to, with the default as the current Environment file name. File: oo-browser.info, Node: Usage, Next: Options, Prev: Environments, Up: Top Using the OO-Browser ******************** * Menu: * Invoking:: Invoking the OO-Browser * Top-Level Classes:: Displaying Top-Level Classes * Moving to Entries:: * Saving Listings:: Writing a Listing to a File * Children and Parents:: Browsing Children and Parents * Descendants and Ancestors:: Browsing Descendants and Ancestors * Viewing and Editing:: Viewing and Editing Classes * Browsing Elements:: * Browsing Categories:: * Browsing Protocols:: * Browsing Implementors:: * Exiting a Listing:: * Quitting and Refreshing:: Quitting and Refreshing the OO-Browser * Using the Mouse:: * Getting Help:: * Locating Entries:: * Filtering Entries:: * Ordering Entries:: * Statistics:: Environment and Class Summaries * Class Info:: Language-Specific Class Information * Adding and Deleting Classes:: * Completing Names:: * Graphical Browsing:: Graphical OO-Browser Interfaces File: oo-browser.info, Node: Invoking, Next: Top-Level Classes, Prev: Usage, Up: Usage Invoking the OO-Browser ======================= The OO-Browser supports the following languages: C++ or G++, C, Info (the online manual format), CLOS (Lisp), Eiffel, Objective-C, Java (as documented in `[Java 95]') and Smalltalk. The OO-Browser may be used on source written in any of these languages by using {`C-c C-o'} or, if that key has not been setup, by using {`M-x oobr RET'}. This command will prompt for the language to browse, the Environment specification of directories to browse, and then will either load the Environment or build it and then display the set of classes (or nodes) in the Environment. (Choose C++ if you are browsing plain C code.) Alternatively, you can invoke the browser on a specific language Environment, e.g. to bring back the last Environment browsed under that language. The language-specific browser invocation commands are: {`M-x eif-browse RET'}, {`M-x c++-browse RET'}, {`M-x info-browse RET'}, {`M-x clos-browse RET'}, {`M-x objc-browse RET'}. A prefix argument given to any of these commands will cause it to prompt for an Environment file to use as the current Environment. On startup, if the selected Environment has been saved to a file, it will be loaded; otherwise, the user will be asked to specify the Environment. The specification will be saved under the previously given file name. The browser will then load this Environment specification file. If the browser loads an Environment file and finds only a specification, it will prompt the user in the minibuffer window with a request to build the Environment. It will continue to prompt the user until a full Environment is built or loaded and then the browser will start, displaying its multi-windowed interface. To abort from these prompts and to cancel the browser invocation request at any time, use {`C-g'} `(keyboard-quit)', the standard way to abort an unfinished command within Emacs. Once an Environment has been loaded, entering and quitting the browser are rapid actions, allowing a smooth transition between editing and browsing. File: oo-browser.info, Node: Top-Level Classes, Next: Moving to Entries, Prev: Invoking, Up: Usage Displaying Top-Level Classes ============================ The OO-Browser starts by displaying all top-level classes in the Environment. "Top-level classes" are those that do not inherit from any others. The browser can show all top-level classes or System or Library classes only. Once in the browser, use: `{s}' System top-level classes only `{l}' Library top-level classes only `{t}' all top-level classes in Environment Note that selection of any of these commands does not affect the ancestry or descendancy trees for any given class. Each simply limits which trees are easily accessible for browsing. For example, selection of Library top-level classes only, followed by the browser show children command, {`c'} `(br-children)', would display the name of a System class if the System class directly inherits from the selected Library class. To see an ordered listing of all of the classes in a particular part of an Environment, use a prefix argument with the commands given above: `{C-u s}' all System classes `{C-u l}' all Library classes `{C-u t}' all Environment classes. File: oo-browser.info, Node: Moving to Entries, Next: Saving Listings, Prev: Top-Level Classes, Up: Usage Moving to Entries ================= Many browser commands operate on the current entry in a listing window. {`C-n'} `(br-next-entry)' moves point to the next entry in a listing buffer. {`C-p'} `(br-prev-entry)' moves to the previous entry. Both take prefix arguments and use them as the number of entries by which to move. File: oo-browser.info, Node: Saving Listings, Next: Children and Parents, Prev: Moving to Entries, Up: Usage Writing a Listing to a File =========================== Many standard editing keys are rebound in listing buffers to provide a useful set of accessible commands. Nonetheless, one needs to be able to store and to edit listing buffers. The {`C-c C-w'} `(br-write-buffer)' command provides this capability. The command prompts for a file name under which to save the current buffer. One may then quit the browser, read in the file and edit it as a plain text file. File: oo-browser.info, Node: Children and Parents, Next: Descendants and Ancestors, Prev: Saving Listings, Up: Usage Browsing Children and Parents ============================= {`c'} displays the children of the class at point; {`p'} displays its parents. {`C-u c'} displays the children of all classes in the present listing window; {`C-u p'} does the same for parents. File: oo-browser.info, Node: Descendants and Ancestors, Next: Viewing and Editing, Prev: Children and Parents, Up: Usage Browsing Descendants and Ancestors ================================== The OO-Browser is very fast at computing ancestor and descendant hierarchies, accounting for multiple inheritance and cycles where permitted. Descendant and ancestor listings provide an immediate overview of some key relationships among class groupings. With point on any class entry line in a listing buffer, {`d'} shows descendants for the class and {`a'} shows ancestors. {`C-u d'} shows the descendant trees for all classes in the current listing buffer and {`C-u a'} does the same for ancestors. The ancestor tree for a given root class is normally shown branching out from the root class. This means that higher-level ancestors, those further away from the root class, are shown in descending trees below lower-level ancestors. The leaves of the tree represent the ancestors furthest from the root, as one might expect. This, however, is the inverse of inheritance trees. Some people prefer to see ancestor trees like inheritance trees, with parents above children. This is an "inverted ancestor tree". To obtain this view of ancestors use {`M- -1 a'} for ancestors of the current class. For ancestors of all classes in the current buffer, use {`M- -2 a'}, or any negative prefix argument lest than -1. Inverted ancestor trees may be made the default by setting `br-invert-ancestors' non-nil, as in: {`M-x set-variable RET br-invert-ancestors RET t RET'} This is a personal setting that affects all Environments used by the browser. File: oo-browser.info, Node: Viewing and Editing, Next: Browsing Elements, Prev: Descendants and Ancestors, Up: Usage Viewing and Editing Classes =========================== One of the major uses of the OO-Browser is to view or edit class source texts. {`v'} will view the source for the class or element name at point in a read-only mode in the viewer window; it will not select the viewer window. {`e'} does the same, except that it edits the element source in a read-write mode, if the user has write permission for the source file. It also selects the viewer window. A prefix argument to either of these commands, as in {`C-u v'} or {`C-u e'}, causes them to prompt for the entry to display. Full class and element name completion is provided once an Environment has been loaded and built. *Note Completing Names::. The value of the variable BR-EDIT-FILE-FUNCTION is the function that the browser calls when a source file entity is displayed for editing. The value of BR-VIEW-FILE-FUNCTION is the function called to view a source file entity. *Note Using an External Viewer or Editor: External Viewing, for information on using non-Emacs editors and viewers with the browser. If a user has no read access rights to a file, this will be apparent when the browser tries to display the file and fails. If the user does not have write permission to the class source file, the standard BR-EDIT-FILE-FUNCTION may display the file in a read-only mode (indicated by two percent signs, %%, at the front of the buffer mode line). This is a warning that one should not attempt to edit the file. In some cases, one really wants to try to edit such a file; in those cases, the buffer may be toggled between read-only and read-write modes via the Emacs command, `(toggle-read-only)', usually bound to {`C-x C-q'}. Once a class has been displayed for viewing, {SPC} will scroll its source text up (forward) almost a windowful; {DEL} will scroll it down (backward) almost a windowful. In fact, this is a general means for scrolling the OO-Browser viewer window whenever point, as shown by the Emacs cursor, is in a listing window. When a class is selected for editing, {`C-v'} will scroll up, {`M-v'} will scroll down, assuming the standard Emacs key bindings. Sometimes one needs to quickly switch back and forth between the viewer window and the current listing window. The normal Emacs window movement commands often are cumbersome in such instances. Instead `(br-to-from-viewer)' bound to {`C-c C-v'}, allows the desired back and forth movement. It acts as a toggle switch, alternately moving between the buffer in the viewer window and the prior listing buffer. By default, the OO-Browser displays class definition files in their entirety. If there are multiple classes in a file, you will be able to scroll through all of them. If you prefer that only the selected class be visible, enable the `br-narrow-view-to-class' option flag. When set to a non-nil value, this flag narrows the source buffer so that only the class of interest and its preceding comments are visible. To examine other classes in the same file, you must execute a {`C-x n w'} `(widen)' command when in the narrowed buffer. (Use {`C-x w'} under Emacs 18.) If the browser is used on a small screen, it may be helpful to use the a full frame to view or edit a buffer of source code. If point is in a listing buffer, pressing {`1'}, the number one, will expand the viewer window buffer to the full frame. When the browser is re-invoked, it will look just as it did before. If point is in the viewer window, {`C-x 1'} `(delete-other-windows)', will do practically the same thing, except that when the browser is re-invoked it will not look precisely as it did before. If point is in a listing window, the buffer displayed in the viewer window may be killed with the {`C-c C-k'} `(br-kill)' command. (A killed buffer is removed from the current Emacs session.) If point is in the viewer window, as it will be after editing a class buffer, use the standard Emacs command {`C-x k'} `(kill-buffer)' instead. File: oo-browser.info, Node: Browsing Elements, Next: Browsing Categories, Prev: Viewing and Editing, Up: Usage Browsing Elements ================= A "feature" of a class is either a routine or attribute defined in the class. An "element" is either a feature or an instance of a class. A number of OO-Browser languages support feature browsing, as documented in *Note Languages::. Instance browsing is only supported in very limited form, for class instances which exist within the code itself. For example, under Common Lisp and CLOS, a default class called `[function]' is defined whose instances are all named functions defined within the environment. A "default class" is a class created to categorize elements of the Environment for browsing; default classes are not specified within the Environment source code. Use {`f'} to display a listing of the features or elements of the class at point, including inherited features. Generally, this includes only routines. Use {`M-0 f'} to turn off the display of inherited features; use the same command again to re-enable display of inherited features. If inherited features are off and there are no feature definitions for the class, the class definition is displayed instead, so that its feature declarations may be browsed. Use {`C-u f'} to display a listing of the features or elements of all classes in the present listing window. Prior versions of the OO-Browser used {`r'} to display features. This key remains for backward compatibility but may be used for another purpose in the future. Move point to an element name and use {`v'} to view its source definition or {`e'} to edit its source. Use {`F'} to see the full signature tag of an element, which includes its argument names and types, if any. {`C-u F'} lists the signatures of all elements in the current listing. This is handy when several elements from the same class have the same name but differ in signature. *Note Using the Mouse::, for how the Action and Assist Keys may be used for browsing elements. File: oo-browser.info, Node: Browsing Categories, Next: Browsing Protocols, Prev: Browsing Elements, Up: Usage Browsing Categories =================== The definition of a "category" is language-specific. Some languages such as Smalltalk use categories to group related classes together. The OO-Browser does not yet support this kind of category. A set of Objective-C categories segments a single class into groupings of related features. When a class category is defined, the category name appears within a set of parentheses, so the OO-Browser displays category names with parentheses around them to distinguish them from classes. The aggregation of all of the categories defined by a class and its ancestors represents the complete class definition. The OO-Browser does support this kind of category. Use the {`C'} key when point is on a class listing entry to obtain a list of the categories defined for the class within the Environment source code (this excludes inherited categories). Use {`C-u C'} to list the categories for all classes in the current listing. Thus, to see the full set of categories for a class, use {`a'} to list the ancestors of the current class and then {`C-u C'} to show all direct and inherited categories of the class. Use {`v'} or {`e'} to view or edit the class category definition associated with a category entry at point. *Note Browsing Implementors::, for an explanation of how to browse the classes that directly implement a category. Use {`f'} with point on the default `[category]' class to list all categories defined in the Environment. File: oo-browser.info, Node: Browsing Protocols, Next: Browsing Implementors, Prev: Browsing Categories, Up: Usage Browsing Protocols ================== The definition of a "protocol" is language-specific. It generally refers to an interface specification to which a class is said to conform. A class conforms to a protocol by implementing the set of features defined in the protocol. Presently, the OO-Browser support protocols only under Objective-C. Objective-C protocols are sometimes called *formal protocols*. Protocol interfaces are specified in a manner similar to classes but their features are only implemented in conforming classes. A single protocol can inherit from any number of other protocols; thus, any conforming class must conform to all of its ancestor protocols. Class definitions list the protocols to which they directly conform, within a set of angle brackets. So the OO-Browser displays protocol names with angle brackets around them to distinguish them from classes. Use the {`P'} key when point is on a class listing entry to obtain a list of the protocols to which the class directly conforms (this excludes inherited protocols). Use {`C-u P'} to list the direct protocols for all classes in the current listing. There is not yet a way to show the complete set of protocols to which a class conforms, which includes all protocols inherited from other protocols and all protocols inherited from ancestor classes. If you use {`P'} when point is on a class' protocol entry, the specification of the protocol will be displayed. Use {`v'} or {`e'} to view or edit the class or class category definition associated with a protocol entry at point. Use standard class browsing keys when on a protocol entry to examine its parents, children, ancestors or descendants. *Note Browsing Implementors::, for an explanation of how to browse the classes that directly conform to a protocol. Use {`f'} with point on the default `[protocol]' class to list all protocols defined in the Environment. File: oo-browser.info, Node: Browsing Implementors, Next: Exiting a Listing, Prev: Browsing Protocols, Up: Usage Browsing Implementors ===================== Sometimes it is important to see the list of classes that define a particular element name. These are called the element's "implementors". With point on an element listing, {`I'} will compute and display the element's implementor list. {`C-u I'} will do the same for all elements in the present listing. Move point to an implementor class name and then use {`v'} or {`e'} to view or edit the element associated with the class. If an element name is defined with different signatures in a single class, the class will be listed as an implementor multiple times. Each class entry can be used to display a different element. {`C-u F'} will display the element signature associated with each class entry in the same order as the class entries in the present listing buffer. File: oo-browser.info, Node: Exiting a Listing, Next: Quitting and Refreshing, Prev: Browsing Implementors, Up: Usage Exiting a Listing ================= When done with a browser listing buffer, one should clear and exit from the buffer's display with {`x'}. This command also displays the previous listing level, if any, and moves point to its previous position within this buffer. In this way, the command provides a quick and clean way to exit back to a previous listing level; you may exit a single level at a time or all the way back to the top-level listing buffer through repeated invocation of the command or by sending a prefix argument value to the command. There is no need to exit from listing buffers to quit from the browser. You may quit, perform other actions, and then re-invoke the browser at the same point from which you left. File: oo-browser.info, Node: Quitting and Refreshing, Next: Using the Mouse, Prev: Exiting a Listing, Up: Usage Quitting and Refreshing the OO-Browser ====================================== {`q'} quits from the browser temporarily. The same command with a prefix argument quits from the browser permanently and kills all non-modified browser buffers. It will not kill any of the class source buffers. If you are familiar with Emacs windowing, you may quickly alter the window configuration of the frame while in the browser, either intentionally or more likely unintentionally. If you execute non-browser Emacs commands while in the browser, you may find other buffers have taken the place of your browser buffers. In either case, you may refresh the browser display and restore it to the way it was when you originally invoked it, by using {`M-x br-refresh RET'} or with {`C-c C-r'} when in a browser listing buffer. File: oo-browser.info, Node: Using the Mouse, Next: Getting Help, Prev: Quitting and Refreshing, Up: Usage Using the Mouse =============== Once configured, mouse control within the OO-Browser is helpful and easy to use. Under InfoDock, XEmacs and Emacs 19, the right mouse button, called the Menu Key, pops up a menu of OO-Browser commands when clicked within an OO-Browser listing buffer. Under XEmacs and Emacs 19, the same menu is added to the menubar used in listing buffers. Under InfoDock with mode-specific menus turned on, the menubar is devoted to OO-Browser commands. Even if the above features are not available to you, if you have mouse support in your Emacs, the following features are available. A single mouse button, called the "Action Key", is used for most purposes. The Action Key is bound to the shift-middle mouse button under standard Emacs, to the middle mouse button under InfoDock, or to the shift-left button on a two-button mouse. A second button, called the "Assist Key", is used for help and other ancillary functions. The Assist Key is bound to the shift-right button. The `br-help-ms' file uses a table format to summarize mouse control within the browser, it may be displayed within the browser via the {`H'} `(br-help-ms)' command. Within an empty listing buffer, clicking the Action Key displays the browser command menu; the Assist Key displays a menu listing language-specific source files. Within this menu, the Action Key selects a buffer for display, the Assist Key marks the buffer for deletion. To perform the deletes, click the Action Key after the last line of the menu. If the Assist Key is clicked after the last line, the deletes are undone and a list of all current editor buffers is shown, allowing you to select buffers other than those containing classes. The mouse buttons can be used to scroll the viewer window a page at a time by clicking after the end of any line. The Action Key scrolls the window up (forward) a windowful and the Assist Key scrolls it down (backward) a windowful. The Action Key acts as follows when in an OO-Browser listing buffer. If the button is pressed: * on a blank line following all entries or in a blank listing buffer, the browser command help menu is displayed in the viewer window exited; * at the beginning of a (non-single character) class name, the class' ancestors are listed; * at the end of an entry line, the listing is scrolled up; * on the `...', following a class name, point is moved to the class descendency expansion; * before an element name, the implementor classes of the name are listed; * anywhere else on an entry line (i.e. on the entry), the entry's source is displayed for editing. The Assist Key acts as follows when in a listing buffer. If it is pressed: * in a blank buffer, a selection list of buffer files is displayed; * at the beginning of a (non-single character) class, the class' descendants are listed; * at the end of an entry line, the listing is scrolled down; * on the `...', following a class name, point is moved to the class expansion; * anywhere else on a class line, the class' elements are listed; * anywhere else on an element line, the element's implementor classes are listed; * on a blank line following all entries, the current listing buffer is exited. File: oo-browser.info, Node: Getting Help, Next: Locating Entries, Prev: Using the Mouse, Up: Usage Getting Help ============ The OO-Browser is very intuitive to operate, but help is always a key or button press away when needed. Besides the online and printed versions of this manual, there is an online quick reference built into the OO-Browser. Once the browser windows appear, press {`h'} at any time to bring up a buffer full of command help. For more extensive documentation on each browser key, use the Emacs command {`C-h k KEY-SEQUENCE'}. File: oo-browser.info, Node: Locating Entries, Next: Filtering Entries, Prev: Getting Help, Up: Usage Locating Entries ================ The {`w'} `(br-where)' command can be used to locate the source file associated with a listing entry. It prints the full pathname of the source file in the minibuffer window. A prefix argument as in, {`C-u w'}, causes the command to prompt for the class or element name to locate. Full completion is provided. *Note Completing Names::. The {`m'} `(br-match)' command provides a quick mechanism for locating any classes in the Environment whose names match to an expression in part or in whole. The browser will prompt for the expression to use. All matching names are displayed in ascending order. By default the expression is treated as a regular expression. A prefix argument sent to the command tells it to treat the expression as a string. After each search, the command reports the number of matching classes found and displays them in the current listing window. It then prompts for another expression to key on. The selected set is then filtered once again. This cycle continues until the {RET} is pressed without giving an expression. This process allows for easy location of desired classes. When the command is invoked (first time through the loop), if the {RET} key is pressed without giving a match expression, the search will match to all classes referenced in the Environment. If you want a regular expression to match to whole class names exclusively, begin it with a '^' and end it with a '$' character which match to beginning of name and end of name, respectively. Thus, "^....$" would match to class names with exactly four characters. A string match always matches to any class name that contains the matching string. File: oo-browser.info, Node: Filtering Entries, Next: Ordering Entries, Prev: Locating Entries, Up: Usage Filtering Entries ================= The {`M'} `(br-match-entries)' command works much like the `(br-match') command described in, *Note Locating Entries::, except that it matches only to entries in the current listing buffer. It thus allows you to filter a listing to just those entries that you care to browse. It prompts you for a regular expression of entries to match and then deletes entries that don't match. A prefix argument sent to the command tells it to treat the match expression as a string. After each search, the command reports the number of matching entries found and displays them in the current listing window. It then prompts for another expression to match. The selected set is then filtered once again. This cycle continues until the {RET} is pressed without giving an expression. This process allows for easy incremental filtering of listings. When the command is invoked (first time through the loop), if the {RET} key is pressed without giving a match expression, the search will match to all entries in the listing, so no filtering will be done. If you want a regular expression to match to whole entries exclusively, begin it with a '^' and end it with a '$' character which match to beginning of line and end of line, respectively. Thus, "^....$" would match to entry lines with exactly four characters. A string match always matches to any entry that contains the matching string. File: oo-browser.info, Node: Ordering Entries, Next: Statistics, Prev: Filtering Entries, Up: Usage Ordering Entries ================ Once you have a desired set of names in a browser listing window, you may want to re-order. For a simple ascending order sort by name, use {`o'}. To sort the lines in the current listing window accounting for leading whitespace, use a positive prefix argument. To sort the lines in descending order accounting for leading whitespace, use a negative prefix argument. Note that all of the top-level class display commands automatically order their output lists. *Note Displaying Top-Level Classes: Top-Level Classes. To sort in descending order, first sort into ascending order with {`o'} to strip any leading whitespace and then use a negative prefix argument to sort the names into descending order. File: oo-browser.info, Node: Statistics, Next: Class Info, Prev: Ordering Entries, Up: Usage Environment and Class Summaries =============================== The {`#'} `(br-count)' command displays in the minibuffer the number of entries in the present listing buffer. The {`M-c'} `(br-class-stats)' command displays in the minibuffer window the number of parents and children for the selected class; with a prefix argument, it prompts for the class name to use. The {`M-e'} `(br-env-stats)' command displays the specification for the current Environment along with a few Environment statistics (OO-Browser version used to build the Environment, total classes, number of System and Library classes, number of duplicate and undefined classes) in the viewer window. With a prefix argument, it displays in the minibuffer window the basic statistics only, leaving the contents of the viewer window intact. File: oo-browser.info, Node: Class Info, Next: Adding and Deleting Classes, Prev: Statistics, Up: Usage Language-Specific Class Information =================================== Presently, this feature is available only for Eiffel browsing. With point on a class name in a listing buffer, the command, {`i'} `(br-entry-info)', displays the class' parents, attributes and routines with routine call summaries. This is its default behavior. {`M-x eif-info-use-short'} will instead cause the `(br-entry-info)' command to run the Eiffel 'short' command on a class, thereby displaying its specification. {`M-x eif-info-use-flat'}, will cause the command to run the Eiffel 'flat' command on a class, thereby displaying its complete feature set. Use {`M-x eif-info-use-calls'} to reset this command to its default behavior. File: oo-browser.info, Node: Adding and Deleting Classes, Next: Completing Names, Prev: Class Info, Up: Usage Adding and Deleting Classes =========================== A file containing class definitions may be added to the Environment with the {`C-c ^'} `(br-add-class-file)' command. This will prompt for the file name, scan the file, and then update the Environment. If a class defined in the file is already in the Environment, its information will be replaced with the information gathered from the file; otherwise, the class will be added to the Environment. This command does not update the browser display; one must issue a browser command after the add command in order to see any change. To add a single class from a file containing multiple classes, read the file into an Emacs buffer, narrow the buffer to the desired class and then execute the add command. *Note Narrowing: (emacs)Narrowing. {`C-c ^'} is normally globally bound in the OO-Browser initialization file, `br-init.el', so that it may be used outside of the browser when editing classes. To delete a class from the Environment, display the class name in a listing window using the {`m'} `(br-match)' command if necessary. (*Note Locating Entries::.) Move point to the desired class name and hit {`C-c C-d'} `(br-delete)' to delete the class. This will remove the class name at point after the class is deleted from the Environment. File: oo-browser.info, Node: Completing Names, Next: Graphical Browsing, Prev: Adding and Deleting Classes, Up: Usage Completing Names ================ Whenever the browser prompts for a name and an Environment has already been loaded or built, one may use the browser's identifier name completion facilities to help in entering the name. These features allow you to type as much of the name as you know and then have the browser fill in what it can. The relevant keys are: {TAB} complete as much as possible of a class or element name {SPC} complete up to one word of the class or element name {`?'} show all possible completions for class or element name You may also use the browser's completion facilities outside of the browser, for example, when editing code. *Note Using Standalone OO-Browser Features: Standalone, and the description of `(br-complete-type)'.